<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>dde manual page - Tcl Bundled Packages</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> dde</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="dde.htm#M2" NAME="L313">NAME</A>
<DL><DD>dde &mdash; Execute a Dynamic Data Exchange command</DD></DL>
<DD><A HREF="dde.htm#M3" NAME="L314">SYNOPSIS</A>
<DL>
</DL>
<DD><A HREF="dde.htm#M4" NAME="L315">DESCRIPTION</A>
<DD><A HREF="dde.htm#M5" NAME="L316">DDE COMMANDS</A>
<DL class="dde commands">
<DD><A HREF="dde.htm#M6" NAME="L317"><B>dde servername </B>?<B>-force</B>? ?<B>-handler </B><I>proc</I>? ?<B>--</B>? ?<I>topic</I>?</A>
<DD><A HREF="dde.htm#M7" NAME="L318"><B>dde execute</B> ?<B>-async</B>? ?<B>-binary</B>? <I>service topic data</I></A>
<DD><A HREF="dde.htm#M8" NAME="L319"><B>dde poke</B> ?<B>-binary</B>? <I>service topic item data</I></A>
<DD><A HREF="dde.htm#M9" NAME="L320"><B>dde request</B> ?<B>-binary</B>? <I>service topic item</I></A>
<DD><A HREF="dde.htm#M10" NAME="L321"><B>dde services </B><I>service topic</I></A>
<DD><A HREF="dde.htm#M11" NAME="L322"><B>dde eval</B> ?<B>-async</B>? <I>topic cmd </I>?<I>arg arg ...</I>?</A>
</DL>
<DD><A HREF="dde.htm#M12" NAME="L323">DDE AND TCL</A>
<DD><A HREF="dde.htm#M13" NAME="L324">EXAMPLE</A>
<DD><A HREF="dde.htm#M14" NAME="L325">SEE ALSO</A>
<DD><A HREF="dde.htm#M15" NAME="L326">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
dde &mdash; Execute a Dynamic Data Exchange command
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>package require dde 1.4</B><BR>
<B>dde servername</B> ?<B>-force</B>? ?<B>-handler </B><I>proc</I>? ?<B>--</B>? ?<I>topic</I>?<BR>
<B>dde execute</B> ?<B>-async</B>? ?<B>-binary</B>? <I>service topic data</I><BR>
<B>dde poke</B> ?<B>-binary</B>? <I>service topic item data</I><BR>
<B>dde request</B> ?<B>-binary</B>? <I>service topic item</I><BR>
<B>dde services </B><I>service topic</I><BR>
<B>dde eval</B> ?<B>-async</B>? <I>topic cmd </I>?<I>arg arg ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
This command allows an application to send Dynamic Data Exchange (DDE)
command when running under Microsoft Windows. Dynamic Data Exchange is
a mechanism where applications can exchange raw data. Each DDE
transaction needs a <I>service name</I> and a <I>topic</I>. Both the
<I>service name</I> and <I>topic</I> are application defined; Tcl uses
the service name <B>TclEval</B>, while the topic name is the name of the
interpreter given by <B>dde servername</B>. Other applications have their
own <I>service names</I> and <I>topics</I>. For instance, Microsoft Excel
has the service name <B>Excel</B>.
<P>
<H3><A NAME="M5">DDE COMMANDS</A></H3>
The following commands are a subset of the full Dynamic Data Exchange
set of commands.
<P>
<DL class="dde commands">
<DT><A NAME="M6"><B>dde servername </B>?<B>-force</B>? ?<B>-handler </B><I>proc</I>? ?<B>--</B>? ?<I>topic</I>?</A><DD>
<B>dde servername</B> registers the interpreter as a DDE server with
the service name <B>TclEval</B> and the topic name specified by <I>topic</I>.
If no <I>topic</I> is given, <B>dde servername</B> returns the name
of the current topic or the empty string if it is not registered as a
service. If the given <I>topic</I> name is already in use, then a
suffix of the form
&ldquo; #2&rdquo;
or
&ldquo; #3&rdquo;
is appended to the name to make it
unique. The command's result will be the name actually used. The
<B>-force</B> option is used to force registration of precisely the
given <I>topic</I> name.
<P>
The <B>-handler</B> option specifies a Tcl procedure that will be called to
process calls to the dde server. If the package has been loaded into a
safe interpreter then a <B>-handler</B> procedure must be defined. The
procedure is called with all the arguments provided by the remote
call.
<P><DT><A NAME="M7"><B>dde execute</B> ?<B>-async</B>? ?<B>-binary</B>? <I>service topic data</I></A><DD>
<B>dde execute</B> takes the <I>data</I> and sends it to the server indicated
by <I>service</I> with the topic indicated by <I>topic</I>. Typically,
<I>service</I> is the name of an application, and <I>topic</I> is a file to
work on.  The <I>data</I> field is given to the remote application.
Typically, the application treats the <I>data</I> field as a script, and the
script is run in the application.  The <B>-async</B> option requests
asynchronous invocation.  The command returns an error message if the
script did not run, unless the <B>-async</B> flag was used, in which case
the command returns immediately with no error.
Without the <B>-binary</B> option all data will be sent in unicode. For
dde clients which don't implement the CF_UNICODE clipboard format, this
will automatically be translated to the system encoding. You can use
the <B>-binary</B> option in combination with the result of
<B><A HREF="../TclCmd/encoding.htm">encoding convertto</A></B> to send data in any other encoding.
<P><DT><A NAME="M8"><B>dde poke</B> ?<B>-binary</B>? <I>service topic item data</I></A><DD>
<B>dde poke</B> passes the <I>data</I> to the server indicated by
<I>service</I> using the <I>topic</I> and <I>item</I> specified.  Typically,
<I>service</I> is the name of an application.  <I>topic</I> is application
specific but can be a command to the server or the name of a file to work
on.  The <I>item</I> is also application specific and is often not used, but
it must always be non-null.  The <I>data</I> field is given to the remote
application.
Without the <B>-binary</B> option all data will be sent in unicode. For
dde clients which don't implement the CF_UNICODE clipboard format, this
will automatically be translated to the system encoding. You can use
the <B>-binary</B> option in combination with the result of
<B><A HREF="../TclCmd/encoding.htm">encoding convertto</A></B> to send data in any other encoding.
<P><DT><A NAME="M9"><B>dde request</B> ?<B>-binary</B>? <I>service topic item</I></A><DD>
<B>dde request</B> is typically used to get the value of something; the
value of a cell in Microsoft Excel or the text of a selection in
Microsoft Word. <I>service</I> is typically the name of an application,
<I>topic</I> is typically the name of the file, and <I>item</I> is
application-specific. The command returns the value of <I>item</I> as
defined in the application.  Normally this is interpreted to be a
string with terminating null.  If <B>-binary</B> is specified, the
result is returned as a byte array.
<P><DT><A NAME="M10"><B>dde services </B><I>service topic</I></A><DD>
<B>dde services</B> returns a list of service-topic pairs that
currently exist on the machine. If <I>service</I> and <I>topic</I> are
both empty strings ({}), then all service-topic pairs currently
available on the system are returned. If <I>service</I> is empty and
<I>topic</I> is not, then all services with the specified topic are
returned. If <I>service</I> is non-empty and <I>topic</I> is, all topics
for a given service are returned. If both are non-empty, if that
service-topic pair currently exists, it is returned; otherwise, an
empty string is returned.
<P><DT><A NAME="M11"><B>dde eval</B> ?<B>-async</B>? <I>topic cmd </I>?<I>arg arg ...</I>?</A><DD>
<B>dde eval</B> evaluates a command and its arguments using the interpreter
specified by <I>topic</I>. The DDE service must be the <B>TclEval</B>
service.  The <B>-async</B> option requests asynchronous invocation.  The
command returns an error message if the script did not run, unless the
<B>-async</B> flag was used, in which case the command returns immediately
with no error.  This command can be used to replace send on Windows.
<P></DL>
<H3><A NAME="M12">DDE AND TCL</A></H3>
A Tcl interpreter always has a service name of <B>TclEval</B>.  Each
different interpreter of all running Tcl applications must be
given a unique
name specified by <B>dde servername</B>. Each interp is available as a
DDE topic only if the <B>dde servername</B> command was used to set the
name of the topic for each interp. So a <B>dde services TclEval {}</B>
command will return a list of service-topic pairs, where each of the
currently running interps will be a topic.
<P>
When Tcl processes a <B>dde execute</B> command, the data for the
execute is run as a script in the interp named by the topic of the
<B>dde execute</B> command.
<P>
When Tcl processes a <B>dde request</B> command, it returns the value of the
variable given in the dde command in the context of the interp named by the
dde topic. Tcl reserves the variable <B>$TCLEVAL$EXECUTE$RESULT</B> for
internal use, and <B>dde request</B> commands for that variable will give
unpredictable results.
<P>
An external application which wishes to run a script in Tcl should have
that script store its result in a variable, run the <B>dde execute</B>
command, and then run <B>dde request</B> to get the value of the
variable.
<P>
When using DDE, be careful to ensure that the event queue is flushed
using either <B><A HREF="../TclCmd/update.htm">update</A></B> or <B><A HREF="../TclCmd/vwait.htm">vwait</A></B>.  This happens by default
when using <B><A HREF="../UserCmd/wish.htm">wish</A></B> unless a blocking command is called (such as <B><A HREF="../TclCmd/exec.htm">exec</A></B>
without adding the <B>&amp;</B> to place the process in the background).
If for any reason the event queue is not flushed, DDE commands may
hang until the event queue is flushed.  This can create a deadlock
situation.
<H3><A NAME="M13">EXAMPLE</A></H3>
This asks Internet Explorer (which must already be running) to go to a
particularly important website:
<P>
<PRE>package require dde
<B>dde execute</B> -async iexplore WWW_OpenURL <A HREF="http://www.tcl.tk/">http://www.tcl.tk/</A></PRE>
<H3><A NAME="M14">SEE ALSO</A></H3>
<B><A HREF="../TkCmd/tk.htm">tk</A></B>, <B><A HREF="../TkCmd/winfo.htm">winfo</A></B>, <B><A HREF="../TkCmd/send.htm">send</A></B>
<H3><A NAME="M15">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#application">application</A>, <A href="../Keywords/D.htm#dde">dde</A>, <A href="../Keywords/N.htm#name">name</A>, <A href="../Keywords/R.htm#remote execution">remote execution</A>
<div class="copy">Copyright &copy; 1997 Sun Microsystems, Inc.
<BR>Copyright &copy; 2001 ActiveState Corporation.
</div>
</BODY></HTML>
